docs/development/Building in Windows.md

   1 # Building in windows
   2
   3 For various reasons, a custom build of Betaflight might be needed. A user might want to enable certain features that are disabled on his / her target, for example. This guide provides the basic instructions needed to build Betaflight on a Windows system. Two options are given:
   4
   5 - Using the Linux subsystem (Windows 10 only)
   6 - Using the Cygwin environment (Windows 7/8/10)
   7
   8 ## Building on Windows 10 using the Linux subsystem
   9
  10 A new feature in Windows 10 allows any developer to quickly and easily run an entire linux subsystem in Windows and access it via a bash terminal. This gives developers full use of the entire Linux OS and all of the great existing linux tools and programs. When Bash for Windows is up and running it feels like you sshed into a full Linux box, except the linux distro is actually running alongside Windows locally.
  11
  12 If you use Bash on Windows you can easily build Betaflight exactly as you would for Ubuntu. [For instructions follow the official guide here.](https://msdn.microsoft.com/commandline/wsl/install_guide)
  13
  14 - https://msdn.microsoft.com/commandline/wsl/install_guide
  15
  16 Once you have Bash On Windows running you can follow the "Building in Ubuntu" instructions for building Betaflight.
  17
  18 ## Building on Windows 7/8/10 using the Cygwin environment
  19
  20 The Cygwin environment provides some functionality similar to a Linux distribution, allowing to build Betaflight in a relatively small (~1 Gb) environment within Windows.
  21
  22 ### Installing Cygwin and required packages
  23
  24 Download the Setup*.exe from https://www.cygwin.com/
  25
  26 ![Cygwin Installation](assets/001.cygwin_dl.png)
  27
  28 Execute the downloaded Setup*.exe and step through the installation  wizard (no need to customize the settings here). Stop at the  "Select Packages" Screen and select the following Packages
  29 for Installation:
  30
  31 - Archive/unzip
  32 - Devel/git
  33 - Devel/bash-completion (was git-completion, Optional)
  34 - Devel/make
  35 - Devel/binutils
  36 - Editors/vim    or  Editors/nano  (file editors, `nano` is most straightforward while `vim` offers more advanced options)
  37 - Shells/mintty (should be already selected)
  38 - Archive/unzip
  39
  40 ![Cygwin Installation](assets/002.cygwin_setup.png)
  41
  42 ![Cygwin Installation](assets/003.cygwin_setup.png)
  43
  44 ![Cygwin Installation](assets/004.cygwin_setup.png)
  45
  46 ![Cygwin Installation](assets/005.cygwin_setup.png)
  47
  48 ![Cygwin Installation](assets/006.cygwin_setup.png)
  49
  50 Continue with the Installation and accept all autodetected dependencies.
  51
  52 ![Cygwin Installation](assets/007.cygwin_setup.png)
  53
  54 The Cygwin environment is now installed and can be used with the `Cygwin-Terminal` application.
  55
  56 ### Clone the Betaflight repository
  57
  58 Head over to the Betaflight Github page and grab the URL of the GIT Repository: "https://github.com/betaflight/betaflight.git"
  59
  60 ![GIT Checkout](assets/011.git_checkout.png)
  61
  62 Open the Cygwin-Terminal, navigate to the `/dev` folder and use the git command `git clone` to checkout the repository.
  63
  64 ```bash
  65 cd /dev
  66 git clone https://github.com/betaflight/betaflight.git
  67 ```
  68 ![GIT Checkout](assets/012.git_checkout.png)
  69
  70 The `/dev/betaflight` folder now holds a copy of the current Betaflight source code repository.
  71
  72 ### Setup GNU ARM Toolchain
  73
  74 To compile the Betafligth source code for the ARM processors used on the various flight controllers, the GNU ARM Toolchain is required. Versions are important, current Betaflight (4.0.0) requires at least ```arm-none-eabi-gcc``` version ```7.3.1```.
  75
  76 The toolchain can be installed in two ways:
  77
  78 - Using the provided `arm_sdk_install` script
  79 - Manual installation
  80
  81 The provided script will install the correct version of the ARM toolchain to the `/dev/betaflight/` directory, which will thus only be avaialble to this project. This method ensures the corerct version is installed and prevents collision with possible other projects you might have.
  82
  83 The manual installation option will install the ARM toolchain system-wide, allowing it to also be used for other projects on the system, should that be necesary.
  84
  85 #### Scripted installation
  86
  87 To install the ARM toolchain, use the `make arm_sdk_install` command within the `/dev/betaflight` directory:
  88
  89 ```
  90 Stefan@DESKTOP-U5FUCGO /dev
  91 $ cd /dev/betaflight
  92
  93 Stefan@DESKTOP-U5FUCGO /dev/betaflight
  94 $ make arm_sdk_install
  95 mkdir -p tools
  96 mkdir -p downloads
  97   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
  98                                  Dload  Upload   Total   Spent    Left  Speed
  99 100   241  100   241    0     0    241      0  0:00:01 --:--:--  0:00:01  1288
 100 100  124M  100  124M    0     0  1965k      0  0:01:05  0:01:05 --:--:-- 2014k
 101 ```
 102
 103 The ARM toolchain is now installed. Note the toolchain can be removed with `make arm_sdk_clean` from the `/dev/betaflight` directory.
 104
 105 #### Manual Installation
 106
 107 Manual installation requires you download the Windows zip ```7.3.1``` (7-2018-q2-update), which can be obtained here:
 108
 109  - https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads (7-2018-q2-update)
 110
 111 Or via direct link:
 112
 113  - https://armkeil.blob.core.windows.net/developer/Files/downloads/gnu-rm/7-2018q2/gcc-arm-none-eabi-7-2018-q2-update-win32.zip
 114
 115 Extract the contents of this archive to any folder of your choice, for instance ```C:\dev\gcc-arm```.
 116
 117 ![GNU ARM Toolchain Setup](assets/008.toolchain.png)
 118
 119 Add the "bin" subdirectory to the PATH Windows environment variable: ```%PATH%;C:\dev\gcc-arm\bin```
 120
 121 ![GNU ARM Toolchain Setup](assets/009.toolchain_path.png)
 122
 123 ![GNU ARM Toolchain Setup](assets/010.toolchain_path.png)
 124
 125 The ARM toolchain is now available within the Cygwin environment.
 126
 127 #### Building the firmware
 128
 129 To compile your Betaflight binaries; open the Cygwin terminal, enter the Betaflight directory and build the project using the `make` command. You can append TARGET=[HARDWARE] if you want to build anything other than the default NAZE target:
 130
 131 ```bash
 132 cd /dev/betaflight
 133 make TARGET=NAZE
 134 ```
 135
 136 ![GIT Checkout](assets/013.compile.png)
 137
 138 Within few moments you should have your binary ready:
 139
 140 ```bash
 141 Stefan@DESKTOP-U5FUCGO /dev/betaflight
 142 $ cd /dev/betaflight
 143
 144 Stefan@DESKTOP-U5FUCGO /dev/betaflight
 145 $ make TARGET=BETAFLIGHTF3
 146 make -j ./obj/betaflight_4.1.0_BETAFLIGHTF3.hex
 147 make[1]: Entering directory '/dev/betaflight'
 148 %% startup_stm32f30x_md_gcc.S
 149 %% (optimised) ./src/main/startup/system_stm32f30x.c
 150 ...
 151 ...
 152 %% (optimised) ./src/main/drivers/usb_io.c
 153 Linking BETAFLIGHTF3
 154 Memory region         Used Size  Region Size  %age Used
 155            FLASH:      241016 B       252 KB     93.40%
 156     FLASH_CONFIG:          0 GB         4 KB      0.00%
 157              RAM:       33568 B        40 KB     81.95%
 158              CCM:          2 KB         8 KB     25.00%
 159        MEMORY_B1:          0 GB         0 GB     -1.#J%
 160    text    data     bss     dec     hex filename
 161  237600    3416   32200  273216   42b40 ./obj/main/betaflight_BETAFLIGHTF3.elf
 162 Creating HEX ./obj/betaflight_4.1.0_BETAFLIGHTF3.hex
 163 ```
 164
 165 Note that the final message will also inform you about flash space use
 166
 167 You can use the Betaflight-Configurator to flash the `obj/betaflight_NAZE.hex` file.
 168
 169 ### Updating and rebuilding
 170
 171 In order to update your local copy of the source code, navigate to the local betaflight repository and use the following steps to pull the latest changes and rebuild your version of betaflight:
 172
 173 ```bash
 174 cd /dev/betaflight
 175 git reset --hard
 176 git pull
 177 make clean TARGET=NAZE
 178 make TARGET=NAZE
 179 ```